Update SCIM_overview.mdx by ocap-kirk · Pull Request #627 · permitio/docs

ocap-kirk · 2026-05-05T18:30:38Z

Summary

Documents multi-tenant SCIM support in the SCIM overview, so a single Permit environment can back multiple isolated customer tenants. Adds a new section to docs/integrations/SCIM/SCIM_overview.mdx.

Why

The SCIM server now supports a tenant-aware URL form, but that capability was undocumented — leaving customers without a clear way to adopt it and the support team without a canonical reference.

Multi-customer environments need isolated role assignments. Customers running one Permit environment across multiple end-customers had no documented way to keep each tenant's user-to-role bindings separate. The tenant-aware URL is the supported mechanism, and it needs to be discoverable.
The URL shape is easy to get wrong. The double /v2/ segment looks like a typo or a protocol version bump. Without an explicit note, users misread it, misconfigure their IdP, or assume it's a SCIM version mismatch. Documenting the routing-prefix-vs-protocol-version distinction prevents misconfiguration and support tickets.
The scoping model is non-obvious. That users and role definitions are environment-scoped while role assignments are tenant-scoped is a subtle but critical detail. Getting it wrong leads to wrong assumptions about isolation (e.g., expecting per-tenant users, or duplicate role definitions). Spelling out the data model sets correct expectations up front.
Backward-compatibility reassurance. Existing single-tenant integrations must keep working. Documenting that the legacy URL is unchanged and continues to route to the default tenant prevents unnecessary migrations.

What's in here

Two supported base URL shapes:
- Legacy (single-tenant): https://scim.permit.io/scim/v2/{permit_project_id}/{permit_env_id} — all role assignments land in the default tenant; existing integrations keep working unchanged.
- Tenant-aware: https://scim.permit.io/scim/v2/{permit_project_id}/{permit_env_id}/v2/{tenant_id} — {tenant_id} is required (there is no tenant-less /v2/Users). Each tenant points its IdP at its own base URL.
A clarifying note that the second /v2/ segment is a routing prefix selecting the multi-tenant SCIM API — not a SCIM protocol version (the SCIM 2.0 version is the earlier /scim/v2/ segment).
{tenant_id} validation rule: [A-Za-z0-9_-]{1,64}; invalid values return a 404 at the routing layer before any handler runs.
How users, groups, and tenants relate:
- Users are environment-scoped — userName stays globally unique within the environment; the tenant segment does not partition users.
- Groups (roles) are environment-scoped definitions — a duplicate displayName reuses the existing role rather than failing.
- Group membership (role assignment) is tenant-scoped — the same user can hold a role in one tenant and not another, independently.
Guidance on choosing between the two URLs (single-tenant vs. multi-customer environments).
Minor typo fix: curly apostrophe → straight apostrophe in the Security bullet.

Linear

PER-15099 — https://linear.app/permit/issue/PER-15099/docs-document-multi-tenant-scim-support-in-scim-overview

netlify · 2026-05-05T18:30:45Z

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	`c04b3d9`
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6a29822588fe780008f24248
😎 Deploy Preview	https://deploy-preview-627--permitio-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

Adds documentation to the SCIM Overview page describing how Permit’s SCIM endpoint behaves in multi-tenant setups, including tenant-aware URL shapes and the scoping rules for users, roles (groups), and role assignments.

Changes:

Fixes a minor formatting/typography issue in the “Security” benefit bullet.
Introduces a new “Multi-tenant SCIM” section explaining supported URL shapes and tenant scoping behavior.
Adds guidance on choosing legacy vs tenant-aware SCIM endpoints.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dshoen619 · 2026-05-10T11:20:47Z

+The SCIM server supports a tenant-aware URL form so a single Permit environment can back multiple isolated customer tenants. Two URL shapes are supported:
+
+- **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged.
+- **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL.


Addressed in beeaa37 — the bullets now lead with a base URL ending at .../{permit_env_id} (legacy) or .../{tenant_id} (tenant-aware), with a leading sentence noting the SCIM client appends the resource path. Matches the convention in OKTA.mdx:36 and EntraID.mdx:55.

dshoen619 · 2026-05-10T11:20:49Z

+- **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged.
+- **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL.


Addressed in beeaa37 — resource endpoints are now listed on their own bullet (.../Users, .../Groups) under each base URL, replacing the ambiguous "...Users and /Groups" phrasing.

dshoen619 · 2026-05-10T11:20:51Z

+- **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged.
+- **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL.


Addressed in beeaa37 — {PROJ_ID}/{ENV_ID} → {permit_project_id}/{permit_env_id} to match OKTA.mdx and EntraID.mdx. Also lowercased TENANT_ID → {tenant_id} for placeholder-style consistency, and added the same "Replace … with …" mapping line that the sibling docs use.

dshoen619 · 2026-05-10T11:20:52Z

+The SCIM server supports a tenant-aware URL form so a single Permit environment can back multiple isolated customer tenants. Two URL shapes are supported:
+
+- **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged.
+- **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL.


Addressed in beeaa37 — added a :::note callout explicitly stating that the second /v2/ is the multi-tenant routing prefix and not a SCIM protocol version. The SCIM 2.0 protocol version is the earlier /scim/v2/ segment. Kept the URL literal since that's the actual API path.

Reframe URL examples as base URLs with resource paths appended by the SCIM client, align placeholder names with sibling Okta/Entra docs ({permit_project_id}, {permit_env_id}, {tenant_id}), and clarify that the second /v2/ segment is the multi-tenant routing prefix rather than a SCIM protocol version. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

zeevmoney

Automated Review - the PR looks clean, found nothing.

linear-code · 2026-06-10T16:06:45Z

PER-15099

Update SCIM_overview.mdx

90ddb95

Copilot AI review requested due to automatic review settings May 5, 2026 18:30

Copilot started reviewing on behalf of ocap-kirk May 5, 2026 18:31 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

dshoen619 assigned dshoen619 and unassigned dshoen619 May 10, 2026

dshoen619 requested review from EliMoshkovich, dshoen619 and gemanor and removed request for dshoen619 May 10, 2026 11:04

dshoen619 self-assigned this May 10, 2026

zeevmoney reviewed Jun 2, 2026

View reviewed changes

zeevmoney and others added 3 commits June 2, 2026 17:35

Merge branch 'master' into ocap-kirk-patch-1

80c1c35

Merge branch 'master' into ocap-kirk-patch-1

9ccca2e

Merge branch 'master' into ocap-kirk-patch-1

c04b3d9

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update SCIM_overview.mdx#627

Update SCIM_overview.mdx#627
ocap-kirk wants to merge 5 commits into
masterfrom
ocap-kirk-patch-1

ocap-kirk commented May 5, 2026 •

edited by dshoen619

Loading

Uh oh!

netlify Bot commented May 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

dshoen619 May 10, 2026

Uh oh!

dshoen619 May 10, 2026

Uh oh!

dshoen619 May 10, 2026

Uh oh!

dshoen619 May 10, 2026

Uh oh!

zeevmoney left a comment

Uh oh!

linear-code Bot commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		- Legacy (single-tenant): `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged.
		- Tenant-aware: `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL.

Conversation

ocap-kirk commented May 5, 2026 • edited by dshoen619 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

What's in here

Linear

Uh oh!

netlify Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for permitio-docs ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

dshoen619 May 10, 2026

Choose a reason for hiding this comment

Uh oh!

dshoen619 May 10, 2026

Choose a reason for hiding this comment

Uh oh!

dshoen619 May 10, 2026

Choose a reason for hiding this comment

Uh oh!

dshoen619 May 10, 2026

Choose a reason for hiding this comment

Uh oh!

zeevmoney left a comment

Choose a reason for hiding this comment

Uh oh!

linear-code Bot commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ocap-kirk commented May 5, 2026 •

edited by dshoen619

Loading

netlify Bot commented May 5, 2026 •

edited

Loading